If you have done any XPage development at all you know the power of using custom controls in your XPage design.  One issue though is if you are using many custom controls on an XPage it is difficult to tell where the XPage design elements start/end and the Custom Control elements start/end.

Version 8.5.1 introduced a new design element that slipped under the radar, but I have found very useful in upgrading my XPage application designs.

This is the new Design Definition property when creating Custom Controls.

As an example look at the design of the following XPage in the XPage design editor.

This is an XPage that is made up of 5 Custom Controls.

• A Header
• Name Fields
• Address Fields
• Buttons
• Footer

Just looking at the design does not tell developers that the elements are Custom Controls.  Plus if this was a large input design, with a big graphics header, designer screen real estate could become a premium.

So what if you could just indicate in the XPage design that there was a Custom Control included without displaying the Custom Control contents?

This is what the new Design Definition Custom Contorl property brings to the table.

To use this new property edit the Custom Control in an 8.5.1 Designer client.  In the Properties view of the Custom Control click on the new Design Definition tab.

This opens an editor that prompts you to "Enter custom XSP markup:"

The XSP markup that is entered in this dialog will be displayed in the XPage design interface instead of the defined elements of the Custom Control.

So here in the Header custom control instead of displaying the company name with the large font I simply want to indicate that this is now a place holder for my Header custom control.

I input the following XSP markup in the Design Definition property

http://www.ibm.com/xsp/core">

Header Custom Control

The code has to be valid XSP markup so it starts with the xml declaration tab and the XSP view tag.

The only other markup added is the XSP panel control with text in between the tags that will describe the functionality of the Custom Control.  Now when this custom control is added to an XPage design instead of seeing all of the Custom Control elements designers will only see the panel with the added text.

Tip:  An easy way to make sure you get the correct markup is to add the control to be used to the design view, then switch to the Source view and cut/paste the correct syntax.

The completed Custom Control looks like the following.

When looking at an XPage design that includes the Custom Control it now looks like the following.

This allows developers to know that there is a custom control there but without taking up a lot of design real estate.

If the same technique was added to the other Custom Controls that make up this XPage design, it would look like the following in the XPage designer

Each of the Custom Controls can be double clicked upon to launch the Custom Control editor to change the contents of the Custom Control.

Nothing changes about the features and functionality of the added Custom Control, all of it properties are still available in the XPage design, it simply un-clutters the design interface.  There is no change in functionality when the XPage is rendered in the Notes or Browser client

You can use any valid XSP design element in the Design Definition property of the Custom Control but as you can see in the following graphic, the Panel control provides a nice placeholder to be displayed in the XPage designer.

You do not have to implement this feature in every custom control added to the page, they can be mixed and matched as the developer requires.

An excellent resource to see how this new feature is implemented is the 8.5.1 Discussion Template.

A special thanks to Steve Castledine for helping me understand this new feature. 

The example applciation that I use here can be downloaded from my website here, but the Discussion Template is a better example once you understand how this new feature is being used.